Specyfikacja interfejsu

Rozwiązanie zakłada użycie HL7 FHIR R4. Rozwiązanie FHIR udostępnia interfejs RESTful API w ustandaryzowany sposób dla zapewnienia interoperacyjności w różnych systemach. Standard FHIR wprowadza model danych dla zapewnienia spójnej interpretacji informacji o procesach realizowanych w ramach opieki zdrowotnej pacjentów - pojęcia w dziedzinie opieki zdrowotnej zostały zdefiniowane i zmapowane na zasoby FHIR. Każdy zasób FHIR posiada profil podstawowy (wynikający ze standardu) z możliwością jego rozszerzania i profilowania na potrzeby konkretnego przypadku użycia. Na potrzeby obsługi sieci KSK wybrano i sprofilowano wybrane zasoby FHIR. Serwer FHIR udostępnia RESTful API do obsługi wybranych zasobów.

Uwierzytelnienie i autoryzacja dostępu do usług serwera FHIR bazuje na standardzie OAuth 2 (szczegóły).

Operacja rejestracji zasobu FHIR

Operacja rejestracji zasobu realizowana jest z wykorzystaniem metody POST protokołu HTTP:

POST https://{adres serwera FHIR}/{podsystem}}/fhir/{typ zasobu}

Zasób FHIR podanego typu (np. CarePlan) przekazywany jest w body. W wyniku operacji, w pozytywnym scenariuszu, serwer FHIR zwraca kod HTTP 201 oraz zarejestrowany zasób wraz z metadanymi, tj. identyfikator logiczny zasobu, wersja czy data rejestracji zasobu czy numer wersji systemu (jeżeli parametry te zostaną przekazane w żądaniu zostaną one zignorowane).

Choć specyfikacja FHIR dopuszcza możliwość nadawania własnego identyfikatora logicznego zasobu (Resource.id), serwer FHIR do obsługi KSK wyklucza taką możliwość - identyfikator logiczny zasobu nadawany jest przez system.

W przypadku niepowodzenia, serwer zwraca odpowiedni kod HTTP wraz z komunikatem o przyczynie niepowodzenia.

Operacja odczytu zasobu FHIR

Operacja odczytu zasobu realizowana jest z wykorzystaniem metody GET protokołu HTTP:

GET https://{adres serwera FHIR}/{podsystem}/fhir/{typ zasobu}/{identyfikator logiczny zasobu (Resource.id)}

W przypadku gdy żądanie zostało zbudowane prawidłowo, serwer zwraca kod odpowiedzi HTTP 200 wraz z odpowiedzią zawierającą wskazany zasób.

W przypadku niepowodzenia, serwer zwraca odpowiedni kod HTTP wraz z komunikatem o przyczynie niepowodzenia.

Operacja wyszukania zasobu FHIR

Operacja wyszukania zasobu realizowana jest z wykorzystaniem metody GET protokołu HTTP:

GET https://{adres serwera FHIR}/{podsystem}/fhir/{typ zasobu}?{parametry_wyszukiwania}

Spowoduje to przeszukanie wszystkich zasobów określonego typu przy użyciu kryteriów przedstawionych w parametrach.

Jeśli wyszukiwanie powiedzie się, serwer zwraca kod HTTP 200, a w treści zwrócony jest zasób Bundle z typem = searchset zawierający wyniki wyszukiwania jako zbiór zero lub więcej zasobów w określonej kolejności.

W przypadku niepowodzenia, serwer zwraca odpowiedni kod HTTP wraz z komunikatem o przyczynie niepowodzenia.

Operacja aktualizacji zasobu FHIR

Operacja aktualizacji zasobu realizowana jest z wykorzystaniem metody PUT protokołu HTTP:

PUT https://{adres serwera FHIR}/{podsystem}/fhir/{typ zasobu}/{identyfikator logiczny zasobu (Resource.id)}

W ramach aktualizacji, w body przekazywany jest kompletny, zaktualizowany zasób. Zasób musi posiadać id zgodny z id w adresie URL. Jeśli zasób posiada versionId i lastUpdated serwer je ignoruje i ustawia prawidłowe wartości. Zaktualizowany zasób FHIR podanego typu (np. CarePlan) przekazywany jest w body. W wyniku operacji, w pozytywnym scenariuszu, serwer FHIR zwraca kod HTTP 200 oraz zaktualizowany zasób wraz z metadanymi, tj. aktualny numer wersji czy datę rejestracji aktualnej wersji zasobu.

W przypadku niepowodzenia, serwer zwraca odpowiedni kod HTTP wraz z komunikatem o przyczynie niepowodzenia.

Niestandardowa operacja aktualizacji

Niestandardowa operacja aktualizacji realizowana jest z wykorzystaniem metody POST protokołu HTTP:

POST https://{adres serwera FHIR}/{podsystem}/fhir/{typ zasobu}/{identyfikator logiczny zasobu (Resource.id)}${nazwa operacji}

Spowoduje to wykonanie operacji na zasobie FHIR o podanym identyfikatorze logicznym.

Jeśli wykonanie operacji powiedzie się, serwer powinien zwrócić kod HTTP 200 wraz z odpowiedzią zawierającą informację o pozytywnym wyniku operacji aktualizacji zasobu podanego typu.

W przypadku niepowodzenia, serwer zwraca odpowiedni kod HTTP wraz z komunikatem o przyczynie niepowodzenia.

Podsystemy P1 wykorzystywane w operacjach na zasobach FHIR

• ekok - podsystem P1 do obsługi elektronicznej Karty Opieki Kardiologicznej
• zm - podsystem P1 do obsługi Zdarzeń Medycznych
• sgoa - podsystem P1 do Gromadzenia Osobistych Danych Medycznych - Ankiety (Moje Zdrowie, 10 dla serca)
• sgr - podsystem P1 do obsługi e-Recepty

Kody błędów odpowiedzi z serwera FHIR

Kod błędu	Opis słowny	Znaczenie
400	Błędne żądanie	Podano nieprawidłowe parametry żądania.
401	Nieautoryzowany dostęp	Klient musi podać aktualne poświadczenia przed dostępem do zasobu lub podał je nieprawidłowe.
403	Zabroniony – serwer zrozumiał zapytanie, lecz konfiguracja bezpieczeństwa zabrania mu zwrócić żądany zasób.	Uwierzytelnienie zostało dostarczone przez klienta, ale uwierzytelniony użytkownik nie może wykonać żądanej operacji ze względu na brak uprawnienia.
404	Nie znaleziono – serwer nie odnalazł zasobu według podanego URL ani niczego co by wskazywało na istnienie takiego zasobu w przeszłości.	Klient wskazał zasób, który nie istnieje.
405	Niedozwolona metoda – metoda zawarta w żądaniu nie jest dozwolona dla wskazanego zasobu.	Klient wskazał nieprawidłową metodę przy wskazywaniu na zasób. Odpowiedź zawiera listę dozwolonych metod.
409	Konflikt – żądanie nie może być zrealizowane, ponieważ występuje konflikt z obecnym statusem zasobu, ten kod odpowiedzi jest zwracany tylko w przypadku podejrzewania przez serwer, że klient może znaleźć przyczyny błędu i przesłać ponownie prawidłowe zapytanie. Odpowiedź serwera powinna zawierać informację umożliwiające klientowi rozwiązanie problemu, jednak nie jest to obowiązkowe	Komunikat zostaje zwrócony w sytuacji nie jednoznacznej np. przesłanie 2 razy identycznego dokumentu, kiedy wymagana jest unikalność.
412	Warunek wstępny nie może być spełniony – serwer nie może spełnić przynajmniej jednego z warunków zawartych w zapytaniu	Niezgodność danych autoryzujących z danymi w dokumencie (np. niezgodność OID, numeru PESEL, daty urodzenia), nieunikalny identyfikator Usługobiorcy lub Zdarzenia Medycznego.
415	Niewspierany typ treści	Klient nie wskazał typu treści (Content Type) w żądaniu lub podał niewspierany format.
422	Żądanie było poprawnie sformułowane, ale nie było zgodne z profilem zasobu	Zasób został odrzucony przez serwer, ponieważ nie jest zgodny z profilem zasobu lub naruszył reguły biznesowe serwera.
500	Wewnętrzny błąd serwera – serwer napotkał niespodziewane trudności, które uniemożliwiły zrealizowanie żądania	Klient przekazał zasób jednak wystąpił nieoczekiwany błąd na serwerze.
501	Nie zaimplementowano – serwer nie dysponuje funkcjonalnością wymaganą w zapytaniu; ten kod jest zwracany, gdy serwer otrzymał nieznany typ zapytania	Dostawca zasobów nie ma obecnie możliwości spełnienia żądania.